package org.go.listener;

import org.go.GoContext;
import org.go.expcetion.GoException;
import org.go.expcetion.WorkExecutionException;
import org.go.scheduler.Scheduler;
import org.go.trigger.Trigger;

/**
 * The interface to be implemented by classes that want to be informed when a
 * <code>{@link org.go.Go}</code> executes. In general,
 * applications that use a <code>Scheduler</code> will not have use for this
 * mechanism.
 * 
 * @see Scheduler#addJobListener(JobListener, Matcher)
 * @see Matcher
 * @see Job
 * @see JobExecutionContext
 * @see WorkExecutionException
 * @see TriggerListener
 * 
 * @author hejie
 */
public interface WorkListener {
	/**
	 * <p>
	 * Get the name of the <code>JobListener</code>.
	 * </p>
	 */
	String getName();

	/**
	 * <p>
	 * Called by the <code>{@link Scheduler}</code> when a <code>{@link org.quartz.JobDetail}</code>
	 * was about to be executed (an associated <code>{@link Trigger}</code>
	 * has occurred), but a <code>{@link TriggerListener}</code> vetoed it's 
	 * execution.
	 * </p>
	 * 
	 * @see #jobToBeExecuted(JobExecutionContext)
	 */
	void jobExecutionVetoed(GoContext context);

	/**
	 * <p>
	 * Called by the <code>{@link Scheduler}</code> when a <code>{@link org.quartz.JobDetail}</code>
	 * is about to be executed (an associated <code>{@link Trigger}</code>
	 * has occurred).
	 * </p>
	 * 
	 * <p>
	 * This method will not be invoked if the execution of the Job was vetoed
	 * by a <code>{@link TriggerListener}</code>.
	 * </p>
	 * 
	 * @see #jobExecutionVetoed(JobExecutionContext)
	 */
	void jobToBeExecuted(GoContext context);

	/**
	 * <p>
	 * Called by the <code>{@link Scheduler}</code> after a <code>{@link org.quartz.JobDetail}</code>
	 * has been executed, and be for the associated <code>Trigger</code>'s
	 * <code>triggered(xx)</code> method has been called.
	 * </p>
	 */
	void jobWasExecuted(GoContext context, GoException jobException);
}